Crate cpython

source ·
Expand description

Rust bindings to the Python interpreter.

§Ownership and Lifetimes

In Python, all objects are implicitly reference counted. In rust, we will use the PyObject type to represent a reference to a Python object.

The method clone_ref() (from trait PyClone) can be used to create additional references to the same Python object.

Because all Python objects potentially have multiple owners, the concept of Rust mutability does not apply to Python objects. As a result, this API will allow mutating Python objects even if they are not stored in a mutable Rust variable.

The Python interpreter uses a global interpreter lock (GIL) to ensure thread-safety. This API uses a zero-sized struct Python<'p> as a token to indicate that a function can assume that the GIL is held.

You obtain a Python instance by acquiring the GIL, and have to pass it into all operations that call into the Python runtime.

§Python 2.7

The library will use the python3 bindings by default. To use the python2 bindings you must specific the python27 feature explicitly in your Cargo.toml.

ⓘ
[dependencies.cpython]
version = "*"
default-features = false
features = ["python27-sys"]

§Error Handling

The vast majority of operations in this library will return PyResult<...>. This is an alias for the type Result<..., PyErr>.

A PyErr represents a Python exception. Errors within the rust-cpython library are also exposed as Python exceptions.

§Example

use cpython::{Python, PyDict, PyResult};

fn main() {
    let gil = Python::acquire_gil();
    hello(gil.python()).unwrap();
}

fn hello(py: Python) -> PyResult<()> {
    let sys = py.import("sys")?;
    let version: String = sys.get(py, "version")?.extract(py)?;

    let locals = PyDict::new(py);
    locals.set_item(py, "os", py.import("os")?)?;
    let user: String = py.eval("os.getenv('USER') or os.getenv('USERNAME')", None, Some(&locals))?.extract(py)?;

    println!("Hello {}, I'm Python {}", user, version);
    Ok(())
}

Re-exports§

Modules§

  • argparse
    This module contains logic for parsing a python argument list. See also the macros py_argparse!, py_fn! and py_method!.
  • buffer
  • exc
    This module contains the python exception types.
  • py_class

Macros§

  • py_argparse
    This macro is used to parse a parameter list into a set of variables.
  • py_capsule
    Macro to retrieve a Python capsule pointing to an array of data, with a layer of caching.
  • py_capsule_fn
    Macro to retrieve a function pointer capsule.
  • py_class
    Defines new python extension class. A py_class! macro invocation generates code that declares a new Python class. Additionally, it generates a Rust struct of the same name, which allows accessing instances of that Python class from Rust.
  • py_exception
    Defines a new exception type.
  • py_fn
    Creates a Python callable object that invokes a Rust function.
  • py_module_initializer
  • pyobject_newtype

Structs§

  • GILGuard
    RAII type that represents the Global Interpreter Lock acquisition.
  • GILProtected
    Mutex-like wrapper object for data that is protected by the Python GIL.
  • NoArgs
    An empty struct that represents the empty argument list. Corresponds to the empty tuple () in Python.
  • PyBool
    Represents a Python bool.
  • PyBytes
    Represents a Python byte string. Corresponds to str in Python 2, and bytes in Python 3.
  • PyCapsule
    Capsules are the preferred way to export/import C APIs between extension modules, see Providing a C API for an Extension Module.
  • PyDict
    Represents a Python dict.
  • PyErr
    Represents a Python exception that was raised.
  • PyFloat
    Represents a Python float object.
  • PyInt
    In Python 2.x, represents a Python long object. In Python 3.x, represents a Python int object. Both PyInt and PyLong refer to the same type on Python 3.x.
  • PyIterator
    A python iterator object.
  • PyLeakedRef
    An immutably borrowed reference to a leaked value.
  • PyLeakedRefMut
    A mutably borrowed reference to a leaked value.
  • PyList
    Represents a Python list.
  • PyLong
    In Python 2.x, represents a Python long object. In Python 3.x, represents a Python int object. Both PyInt and PyLong refer to the same type on Python 3.x.
  • PyModule
    Represents a Python module object.
  • PyNone
    An empty struct that represents None in Python.
  • PyObject
    Represents a reference to a Python object.
  • PySequence
    Represents a reference to a python object supporting the sequence protocol.
  • PySet
    Represents a Python set.
  • PySharedRef
    A reference to PySharedRefCell owned by a Python object.
  • PySharedRefCell
    A mutable memory location shareable immutably across Python objects.
  • PyString
    Represents a Python string. Corresponds to basestring in Python 2, and str in Python 3.
  • PyTuple
    Represents a Python tuple object.
  • PyType
    Represents a reference to a Python type object.
  • PyUnicode
    Represents a Python string. Corresponds to basestring in Python 2, and str in Python 3.
  • Python
    Marker type that indicates that the GIL is currently held.
  • PythonObjectDowncastError
  • UnsafePyLeaked
    An immutable reference to PySharedRefCell value, not bound to lifetime.

Enums§

Traits§

  • FromPyObject
    FromPyObject is implemented by various types that can be extracted from a Python object.
  • NumberProtocol
    Operations on numeric objects
  • ObjectProtocol
    Trait that contains methods
  • PyClone
  • PyDrop
  • PythonObject
    Trait implemented by all Python object types.
  • PythonObjectWithCheckedDowncast
    Trait implemented by Python object types that allow a checked downcast.
  • PythonObjectWithTypeObject
    Trait implemented by Python object types that have a corresponding type object.
  • RefFromPyObject
    RefFromPyObject is implemented by various types that can be extracted as a reference from a Python object. Depending on the input object, the reference may point into memory owned by the Python interpreter; or into a temporary object.
  • ToPyObject
    Conversion trait that allows various objects to be converted into Python objects.

Functions§

Type Aliases§